fix(gem): warn when the hosted redirect leaves a stale unpatched install materialized - #219

Defect (D2, 2026-08-19 gem live-matrix — verified 3/3 in fresh containers)

scan --mode hosted for gems is a pure Gemfile/Gemfile.lock text rewrite with no stale-install handling. The natural user chain — bundle install first (gem materialized under BUNDLE_PATH), hosted redirect second — leaves the next bundle install inert: exit 0, Using activestorage 6.0.3, no refetch. The installed files and the cached .gem stay UPSTREAM/UNPATCHED while Gemfile + lock claim the patched registry. Silent, zero warnings, CVE stays live.

Empirical scoping (this PR's campaign, fresh containers, real prod patch pkg:gem/activestorage@6.0.3, uuid 15e960b5-f432-4b6c-b8aa-534a2b419323)

Verdict: the defect is universal — the warning is emitted on every bundler major, and the remedy prescribes removal + bundle install, never --force/--redownload.

Fix (CLI-side, read-only — no rewriter changes)

After the gem hosted rewrite, run_redirect probes the project's installed-gem discovery paths — the existing RubyCrawler::get_gem_paths + find_by_purls APIs the apply flow uses (vendor/bundle/<engine>/<ver>/gems deployment layouts, or the gem env homes for non-deployment installs) — for each confirmed gem redirect, and hash-compares the materialization against the patch record's afterHash file map (verify_file_patch, the same primitive vex verification uses):

• every file at afterHash → already patched, never warns — this is the one check that cannot false-positive: an agent-mode apply patches the installed tree in place while the cached .gem stays upstream, so the (also-considered) cache-sha comparison would cry wolf on every agent→hosted migration and was rejected;
• anything else → a loud redirect_gem_stale_install warning in both the JSON envelope (redirect.warnings[]) and text output (code-tagged stderr line), naming the installed dir, the cache .gem, and the specifications entry, and prescribing the verified remedy;
• read-only by contract: nothing is ever deleted (no destructive deletion by default); no bundler-version floor;
• skipped on --dry-run (nothing rewritten, no records fetched) and when the patch record could not be fetched (record_fetch_failed already fired — no afterHash map, no sound judgment); re-fires on idempotent re-scans until the stale materialization is gone.

Live verification of the FIX (fixed binary in the containers, real prod patch)

• bundler 4.0.18: end-to-end green — the warning fires naming the exact on-disk paths; following its prescription installs the patched gem (cache sha 52d9c99a5f87…, Socket Community Patch marker present).
• bundler 1.17.3: no warning yet, no false positive — bundler 1's FLAT BUNDLE_PATH layout (vendor/bundle/gems/..., no ruby/<ver> scoping) is not discovered by today's crawler. Synergy with the in-flight crawler PR: detection goes through RubyCrawler::get_gem_paths, so the parallel flat-BUNDLE_PATH crawler extension makes this probe cover bundler 1 automatically — deliberately not duplicated here.

Tests (test-first, RED→GREEN)

• New hermetic, non-ignored e2e tests/e2e_redirect_gem_stale_install.rs (real binary + wiremock, hand-laid deployment layout, no ruby/gem/bundler needed): stale materialization → exactly one warning naming all three paths + the remedy, tree untouched, stderr mirror on the human path (RED before the fix — verified failing with only redirect_gem_no_checksums_section/redirect_gem_frozen_install present); already-patched materialization → quiet; fresh checkout → quiet.
• New unit tests in scan/hosted.rs: warning text (paths + verified remedy + --force/--redownload called out as non-remedies), afterHash judgment (patched/upstream/tampered/missing), probe end-to-end over a temp deployment layout (stale/patched/missing-record/zero-file-record/non-gem), uuid-fallback record lookup.

test result: ok. 16 passed; 0 failed; 0 ignored; 0 measured; 395 filtered out   (--lib commands::scan::hosted)
test result: ok. 3 passed; 0 failed; 0 ignored                                   (e2e_redirect_gem_stale_install)
test result: ok. 1 passed; 0 failed; 0 ignored                                   (redirect_golden)
test result: ok. 410 passed; 0 failed; 1 ignored                                 (socket-patch-cli --lib)

Plus in_process_redirect, in_process_redirect_pnpm, e2e_vex_redirect all green; cargo fmt --check clean on touched files; cargo clippy --lib --test e2e_redirect_gem_stale_install -- -D warnings clean.

Golden suite / depscan twin

cargo test -p socket-patch-core --test redirect_golden — green, untouched. The probe is CLI-side only; rewrite_gem and every fixture byte are unchanged, so no re-bless and no depscan gem.ts lockstep change is required for this PR. (The depscan hosted PR flow has no install-side context to probe; if the backend ever wants the equivalent guard, it is a separate design.)

Contract

• CLI_CONTRACT.md: new "Gem stale-install guard" paragraph in the hosted-mode contract + a redirect_gem_stale_install row in the stable-tags vocabulary table (additive = MINOR per the table's own note).
• docs/ecosystems.md: gem hosted column notes the guard.

🤖 Generated with Claude Code

Round 2 — adversarial review + Windows CI (commit 97771c8)

CI was RED on test (windows-latest) exactly as the review predicted: the round-1 unit tests substring-matched forward-slash/mixed-separator literals against Path::join output (backslash-joined on Windows). All fixed, plus the review's triaged findings:

MUST-FIX, all done:

1. Windows paths — every compared path (unit + e2e, fixtures included) is now built with the same component-wise joins production uses; expected strings come from display() of identically-constructed PathBufs. The only remaining slash literal is a URL assert.
2. --global/--global-prefix threading — the probe's CrawlerOptions mirrors scan's own discovery (was hardcoded false/None); pinned by gem_stale_probe_honors_global_prefix.
3. Same-run --vex contradiction — the probe returns GemStaleOutcome { warnings, stale_purls }; stale purls are excluded from assume_applied, falling back to installed-tree verification (patched installs still attest with hash evidence; stale ones are omitted, and an all-stale --vex run fails per the embedded-VEX contract instead of attesting a live CVE). Pinned by gem_hosted_stale_purl_is_not_vex_attested_in_the_same_run.
4. Re-fire guarantee — record lookup is uuid-keyed, fresh records first then the redirect ledger's persisted ones; a transient /patches/view 5xx can no longer silently retire the warning. Pinned by gem_hosted_stale_warning_refires_when_record_fetch_fails (view 200 once, 500 after) + a unit twin.
5. One shared oracle — core's vex::verify::verify_patch_record is now pub; the probe's duplicate gem_install_matches_record is deleted.
6. False-positive hardening — staleness needs positive evidence: at least one record file whose bytes were actually read (current_hash present) and hash to neither expectation; missing/unreadable files (verify_file_patch folds IO errors into NotFound) never warn. Variant purls resolving to one installed dir stay quiet when ANY record judges it patched. Both pinned (gem_stale_positive_evidence_requires_readable_mismatched_bytes, gem_stale_probe_variant_records_stay_quiet_when_any_judges_patched).

SHOULD-FIX, all done: (7) committed vendor/cache/<leaf>.gem joins a project-local delete list (bundler installs from it first — a remedy leaving it behind silently reinstates stale bytes), and a sha256-mismatched committed archive warns standalone so a fresh checkout with a committed stale cache is no longer silent (sha from the registry override's gemChecksumSha256, hashed via core's file_sha256_hex; unreadable → no evidence → quiet); (8) shared gem-env homes get a prefer-project-local-bundle-path remedy instead of an unconditional delete prescription; (9) non-UTF8 dir leaves are skipped, the unreachable no-parent arm is an expect() invariant (per #198 convention); (10) record availability folds into the candidate filter with an early return before any crawler work or gem env spawn — the --dry-run gate at the call site stays deliberately explicit (review asked for "derived", but the round's own ledger fallback (4) breaks the derivation: a dry-run over an already-redirected project would otherwise warn about state the run didn't create — documented at the gate); (11) OR-assert split (code tag AND path asserted separately), two-gem-home multiplicity e2e added, e2e migrated onto tests/common/mod.rs run_with_env/parse_json_envelope (SOCKET_NO_UPDATE_CHECK now covered); (12) uuid-only lookup replaces purl-then-uuid (the fallback-only test became the uuid-keyed lookup test); (13) prose deduped — CLI_CONTRACT's "Gem stale-install guard" is the one canonical narrative, the table row / ecosystems.md / fn docs / e2e header are sentence + pointer, and the warning details keep only the load-bearing remedy text.

Skipped per triage (follow-ups): the pypi/composer sibling stale hazards (same structural issue — hosted rewrite is pure lockfile text with no stale-install handling; needs its own campaign), loop-inversion batching of locate_gem_dir, repair.rs integration beyond the one-liner (its hosted-skip message now notes the re-scan "also re-checks for stale pre-redirect installs").

Round-2 gates (all green):

cargo clippy --workspace --all-features -- -D warnings   (the exact CI invocation): clean
cargo test -p socket-patch-cli --lib:                    ok. 419 passed; 0 failed; 1 ignored
e2e_redirect_gem_stale_install:                          ok. 19 passed; 0 failed
e2e_vex_redirect / in_process_redirect / in_process_redirect_pnpm / repair_invariants:
                                                         ok. 5 / 41 / 8 / 20 passed; 0 failed
cargo test -p socket-patch-core --test redirect_golden:  ok. 1 passed (untouched, no re-bless)
cargo test -p socket-patch-core --lib vex::verify:       ok. 27 passed
rustfmt --check on all touched files:                    clean